fig-financial-payments-b2b-xapi

1.0.x
(0 reviews)

Webhook: Payment Status Update

Overview

The Fidelidade Financial Platform provides real-time webhook notifications to keep partners informed of payment status changes. Instead of polling the API, your system receives automatic HTTP POST notifications when events occur, enabling efficient and timely updates.

1. Configuration

To receive webhook notifications, register your endpoint with the Fidelidade integration team. Contact the team via email and provide:

  • Endpoint URL: The full HTTPS URL where webhook payloads will be sent.
  • Authentication Method: Specify the authentication type and credentials for MuleSoft to access your endpoint.

Supported Authentication Methods

MethodRequirements
Basic AuthUsername and password.
API Key (Header)Header name (e.g., X-API-Key) and key value.
OAuth 2.0 (Client Credentials)Token Server URL, Client ID, and Client Secret.

2. Event Payload Structure

Webhook notifications are sent as HTTP POST requests with a JSON body (application/json). Each notification follows the structure below.

Example Payload: payment.status.updated

{
  "eventId": "a8ca3d79-c28d-4302-9414-b3433f6d40ec",
  "eventType": "payment.status.updated",
  "timestamp": "2024-11-04T18:45:23Z",
  "data": {
    "paymentSessionId": "0eb9cad4-48be-41d2-81e0-d66b568141cb",
    "status": "Terminated",
    "successful": false
  }
}

3. Payload Field Definitions

FieldTypeDescription
eventIdString (UUID)Unique identifier for the webhook event. Use for idempotency to prevent duplicate processing. Correlates with the internal correlationId for troubleshooting.
eventTypeStringType of event. Always payment.status.updated for this feature.
timestampString (ISO 8601)UTC date and time when the event was generated.
dataObjectContains details about the payment status change.
data.paymentSessionIdString (UUID)Unique identifier of the affected payment session.
data.statusStringNew payment status. Values: Pending, Processing, Succeeded, Failed, Terminated, Cancelled.
data.successfulBooleanIndicates if the status is a successful (true) or failed (false) final state.

4. Implementation Guide

To ensure reliable integration, your webhook endpoint must adhere to these best practices:

4.1 Respond Promptly with 200 OK

  • ✅ Do: Return an HTTP 200 OK immediately upon receiving the webhook.
  • 🚫 Do not: Perform long-running tasks (e.g., database operations) before responding.
  • ⏱️ Timeout: The platform waits up to 10 seconds for a response.
  • 💡 Tip: Queue the payload for asynchronous processing and respond immediately.

4.2 Ensure Idempotency

  • Use the eventId to check for previously processed events.
  • If the eventId exists in your system, ignore the event but still respond with 200 OK.

4.3 Retry Policy

If your endpoint:

  • Fails to return a 2xx status,

  • Returns a 4xx or 5xx error, or

  • Does not respond within 10 seconds,

the platform marks the delivery as failed and retries using exponential backoff until a 200 OK is received.

4.4 Security Recommendations

To validate webhook requests:

  • Restrict accepted IP ranges to Fidelidade’s webhook servers.

  • Verify the digital signature in the webhook header (if configured).

  • Validate authentication credentials (Basic Auth, API Key, or OAuth) provided during registration.

Result

Once configured, webhook notifications deliver secure, real-time payment status updates, eliminating the need for polling and ensuring efficient integration with the Fidelidade Financial Platform.

Reviews